核身

人脸识别认证

接口地址:/identity/face

请求方式:POST

请求数据类型:application/json

响应数据类型:*/*

开发者:张辉

接口描述:

纯API

请求示例:

{
  "systemId": "",
  "name": "",
  "certType": "INDIVIDUAL_CH_IDCARD",
  "idNo": "",
  "faceauthMode": "",
  "faceInterfaceType": "H5",
  "resultPage": 0,
  "callbackUrl": "",
  "contextId": "",
  "notifyUrl": "",
  "config": {
    "audioVideoTemplateId": "",
    "audioVideoActiveField": {}
  },
  "mobileNo": "",
  "certificationPurpose": "",
  "orgName": "",
  "orgCertNo": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
identityFaceDTO IdentityFaceDTO body true IdentityFaceDTO IdentityFaceDTO
  systemId 业务系统id true string
  name 姓名 true string
  certType 个人证件类型
INDIVIDUAL_CH_IDCARD - 中国大陆身份证（默认值）
INDIVIDUAL_CH_TWCARD - 台湾来往大陆通行证（台胞证）
INDIVIDUAL_CH_HONGKONG_MACAO - 港澳来往大陆通行证（回乡证）
INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW - 港澳台居民居住证（18位810开头）
INDIVIDUAL_CH_GREEN_CARD - 外国人永久居留身份证（18位9开头）		 false string
  idNo 身份证号 true string
  faceauthMode 刷脸认证方式
ZHIMACREDIT - 支付宝刷脸认证（https://open.esign.cn/doc/opendoc/identity_service/ivkwc365m7diz85l）
TENCENT - 腾讯云刷脸认证（https://open.esign.cn/doc/opendoc/identity_service/ivkwc365m7diz85l）
ESIGN - 快捷刷脸认证（https://open.esign.cn/doc/opendoc/identity_service/ivkwc365m7diz85l）
WE_CHAT_FACE - 微信小程序刷脸（https://qianxiaoxia.yuque.com/opendoc/csbcpa）
PSN_AUDIO_VIDEO_ESIGN - 智能视频认证 （https://open.esign.cn/doc/opendoc/identity_service/ivkwc365m7diz85l）
以下方式需联系e签宝技术人员开通后方可使用：
FACE_TIKTOK_MINI - 抖音小程序刷脸（【https://qianxiaoxia.yuque.com/opendoc/csbcpa）		 true string
  faceInterfaceType 刷脸对接方式
H5 - 纯H5刷脸（默认值）
SDK - APP内集成SDK刷脸（仅限faceauthMode为TENCENT- 腾讯云刷脸方式，且是APP内刷脸场景使用）
（点击跳转 移动端SDK对接说明 https://open.esign.cn/doc/opendoc/identity_service/hvcl6qguq1y108vt）		 false string
  resultPage 是否展示e签宝刷脸结果页，默认：0（不展示）
1 - 展示
0 - 不展示
【注】：展示结果页时，如果用户刷脸失败，结果页会返回失败原因		 false integer(int32)
  callbackUrl 认证完成后重定向地址
（可以在用户刷脸完跳转到贵司重定向地址后，调用【查询个人刷脸状态】接口主动查询用户刷脸结果：成功/失败）
【注】：
微信小程序刷脸 和 APP内集成SDK刷脸方式可以不传该字段
地址最长2048字符		 false string
  contextId 自定义业务标识
（用于关联开发者的业务系统，将在异步通知时发送回开发者，标识自身业务）		 false string
  notifyUrl 认证结束后异步通知地址（详见 https://open.esign.cn/doc/opendoc/identity_service/awa4m6 章节说明） false string
  config 认证配置项 false Config Config
    audioVideoTemplateId 智能视频认证模板ID（可以指定录制视频页面的朗读文案）
【注】：
仅在faceauthMode：PSN_AUDIO_VIDEO_ESIGN - 智能视频认证 场景使用
请联系e签宝技术人员配置后提供		 false string
    audioVideoActiveField 智能视频认证文案中的动态朗读内容，动态内容 Key:Value值（支持自定义key和Value），格式如下：
"audioVideoActiveField": {"appName": "开发者平台名","userName": "认证人姓名","bizScene":"签署的文件名"}【注】：
与 audioVideoTemplateId（智能视频认证模板ID）配套使用
请联系e签宝技术人员进行配置		 false object
  mobileNo 人脸认证授权手机号
【注】：
用户刷脸认证完成后，当前证件号可绑定该手机号，后续可以用该手机号发起意愿验证码确认，详情参考【人脸授权手机号意愿认证】模块
需联系e签宝技术人员确认相关配置是否开启后，才可使用		 false string
  certificationPurpose 本次实名用途，默认：INDIVIDUAL（个人认证）
INDIVIDUAL - 个人认证
ORGANIZATION - 企业认证
【注】：
后续企业认证由法定代表人本人作为经办人认证时可传入ORGANIZATION，用于展示企业数字证书服务协议
后续通过【4要素】企业核身认证 接口传入当前认证流程id，并通过企业四要素核验可直接完成企业实名，无需后续步骤
需联系e签宝技术人员确认相关配置是否开启后，才可使用		 false string
  orgName 企业名称（本次实名用途为企业认证时需传入）
【注】：
certificationPurpose传ORGANIZATION时必须传入需保证当前企业名称和后续【4要素】企业核身认证 接口传入的企业账号中的企业名称一致		 false string
  orgCertNo 企业证件号（本次实名用途为企业认证时需传入）
【注】：
certificationPurpose传ORGANIZATION时必须传入需保证当前企业证件号和后续【4要素】企业核身认证 接口传入的企业账号中的企业证件号一致		 false string

响应状态:

状态码 说明 schema
200 OK RIdentityFaceVO

响应参数:

参数名称 参数说明 类型 schema
code integer(int32) integer(int32)
message string
data IdentityFaceVO IdentityFaceVO
  flowId 实名认证流程ID string
  authUrl 刷脸认证短链接
指定TENCENT（腾讯云刷脸认证）时，链接有效时长为2分钟；
指定ZHIMACREDIT（支付宝刷脸认证）时，链接有效时长为23小时；
指定ESIGN（快捷刷脸认证）时，链接有效时长为60分钟；
（如果用户超过链接有效期未操作，需要重新发起新的流程获取新的链接给用户操作）		 string
  originalUrl 刷脸认证长链接
指定TENCENT（腾讯云刷脸认证）时，链接有效时长为2分钟；
指定ZHIMACREDIT（支付宝刷脸认证）时，链接有效时长为23小时；
指定ESIGN（快捷刷脸认证）时，链接有效时长为60分钟；
（如果用户超过链接有效期未操作，需要重新发起新的流程获取新的链接给用户操作）		 string
  expire 链接失效时间（Unix时间戳格式，单位：毫秒） integer(int64)
  faceToken 刷脸令牌
（仅限腾讯云-SDK刷脸和微信小程序刷脸方式使用，其他情况不返回内容）
腾讯云SDK刷脸的faceToken有效期为2分钟
微信小程序刷脸的faceToken有效期为2小时		 string

响应示例:

{
    "code": 200,
    "message": "",
    "data": {
        "flowId": "",
        "authUrl": "",
        "originalUrl": "",
        "expire": 0,
        "faceToken": ""
    }
}

人脸识别认证结果查询

接口地址:/identity/face/{flowId}

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

开发者:张辉

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
flowId path true string

响应状态:

状态码 说明 schema
200 OK RIdentityFaceResultVO

响应参数:

参数名称 参数说明 类型 schema
code integer(int32) integer(int32)
message string
data IdentityFaceResultVO IdentityFaceResultVO
  status 刷脸结果状态
ING - 刷脸地址已申请
SCAN - 刷脸地址已使用，但尚未接收到刷脸结果（仅限e签宝认证服务网页版PC端展示二维码，手机扫码刷脸场景）
SUCCESS - 刷脸认证通过
FAIL - 刷脸认证失败		 string
  message 刷脸结果描述 string
  similarity 刷脸照片相似度得分（目前腾讯云刷脸和快捷刷脸才会返回具体值） string
  livingScore 刷脸活体检测得分（目前腾讯云刷脸和快捷刷脸才会返回具体值） string
  failedReasonCode 刷脸失败的错误码
1445034 - 当前浏览器不支持该认证方式，请使用其他浏览器操作
1445035 - 当前设备不支持该认证方式，请使用其他设备操作
1445700 - 认证表达结果与标准答案不一致
1445902 - 姓名或身份证号有误
1445813 - 眼睛被遮挡，请检测眼镜或周围光线
1445900 - 无法判断为同一人，请确认身份后重试
1445702 - 语音识别服务异常
1445910 - 证件号格式有误
1445701 - 认证视频用户回答音频无声音
1445409 - 网络不给力,请稍后再试
1445909 - 姓名格式有误
1445011 - 认证失败
1445907 - 比对相似度未达到通过标准
1441001 - 疑似非真人，请确保本人操作且正脸对框
1441002 - 高风险设备
1445023 - 光线太强，请到室内识别
1440035 - 未检测到人脸		 string
  failedReason 刷脸失败的原因，返回failedReasonCode错误码对应的原因 string
  faceSupplierType 刷脸底层供应商通道
WE_CHAT - 微信小程序刷脸
TECENT_CLOUD - 腾讯云刷脸（腾讯H5刷脸通道）
TECENT_CLOUD_SDK - 腾讯云刷脸（腾讯SDK刷脸通道）
HUOSHAN - 快捷刷脸（字节火山刷脸通道）
DOUYIN_MINI - 抖音小程序刷脸
ANT_H5 - 快捷刷脸（蚂蚁H5刷脸通道）
MEGVII_H5 - 快捷刷脸（旷视H5刷脸通道）
MEGVII_SDK - 快捷刷脸（旷视SDK刷脸通道）
ALIPAY_MINI- 支付宝刷脸（支付宝小程序刷脸通道）
ANT_MINI - 支付宝刷脸（蚂蚁区块链小程序刷脸通道）		 string
  faceVisionResult 刷脸面部视觉识别结果（部分字段底层供应商不支持时返回为空）
以下字段都是根据刷脸识别预估的结果，不一定准确		 FaceVisionResult FaceVisionResult
    gender 性别
0 - 预估为男性
1 - 预估为女性		 string
    estimatedAge 预估年龄
注：根据刷脸供应返回的视觉年龄与用户实际年龄（身份证年龄）差值		 string
    isAgeDifference 视觉年龄差
注：根据刷脸供应返回的视觉年龄与用户实际年龄（身份证年龄）差值		 string
    isLargeAgeDifference 是否年龄差大
Y - 是
N - 否		 string
    idAttacked 身份证是否被冒用
Y - 是
N - 否		 string
    faceAttack 是否活体攻击
Y - 是
N - 否		 string
    faceReplaced 是否换脸攻击
Y - 是
N - 否		 string
    genderRisk 是否异性
Y - 是
N - 否
注：据刷脸供应返回的视觉性别与用户实际性别（身份证倒数第二位，如果是非大陆人士，则返回为空）		 string

响应示例:

{
    "code": 0,
    "message": "",
    "data": {
        "status": "",
        "message": "",
        "similarity": "",
        "livingScore": "",
        "failedReasonCode": "",
        "failedReason": "",
        "faceSupplierType": "",
        "faceVisionResult": {
            "gender": "",
            "estimatedAge": "",
            "isAgeDifference": "",
            "isLargeAgeDifference": "",
            "idAttacked": "",
            "faceAttack": "",
            "faceReplaced": "",
            "genderRisk": ""
        }
    }
}

核身 获取个人核身认证地址

接口地址:/identity/indivAuthUrl

请求方式:POST

请求数据类型:application/json

响应数据类型:*/*

开发者:张辉

接口描述:

获取个人实名认证地址，页面中集成了人脸识别认证、银行卡认证以及手机认证三种认证方式，用户可以自主选择其中一种认证方式。
【注】核身认证无需提前为用户创建账号；
请求参数示例：
{ "authType": "PSN_BANK4_AUTHCODE", "availableAuthTypes":["PSN_TELECOM_AUTHCODE","PSN_BANK4_AUTHCODE","PSN_FACEAUTH_BYURL"], "authAdvancedEnabled":["PSN_BANK4_AUTHCODE","PSN_TELECOM_AUTHCODE"], "contextInfo": { "contextId": "993de698a82b43d9ba6a4fb26093629e", "notifyUrl": "http://172.xx.xx.10:8080/notify/msgRecive", "redirectUrl": "https://www.xx.cn/", "showResultPage": true }, "indivInfo": { "name": "", "certNo":"41042**555" }, "configParams": { "indivUneditableInfo": ["name", "certNo", "mobileNo", "bankCardNo"] } }
返回参数示例：
{ "code": 0, "message": "成功", "data": { "url": "https://smlfront.esign.cn:8890/identity/login?param=kYuzrh111WOEGN5VYx6Uz5x9D%2B4cM0whriPJ5Mm1ZOYySdqYp7HRJCeAg7FqO%2F4QJiPeb6FLyWnTT1Laz8uQK9ki4oWF9eQsE%2B1ZFb4wY%3D&appId=4438864954&indiversion=official3.1&lang=zh-CN", "shortLink": "https://smlt.esign.cn/yCg11JIK", "flowId": "4437741111615429144" } }

请求示例:

{
  "systemId": "",
  "authType": "",
  "availableAuthTypes": [],
  "authAdvancedEnabled": [],
  "receiveUrlMobileNo": "",
  "indivInfo": {
    "bankCardNo": "",
    "certNo": "",
    "certType": "",
    "mobileNo": "",
    "name": ""
  },
  "configParams": {
    "indivUneditableInfo": [],
    "audioVideoTemplateId": "",
    "audioVideoActiveField": {}
  },
  "contextInfo": {
    "contextId": "",
    "notifyUrl": "",
    "origin": "",
    "redirectUrl": "",
    "showResultPage": true,
    "maxFrequencyLimit": "",
    "failRedirectUrl": ""
  },
  "certificationPurpose": "",
  "orgName": "",
  "orgCertNo": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
identityAuthUrlDTO IdentityAuthUrlDTO body true IdentityAuthUrlDTO IdentityAuthUrlDTO
  systemId 业务系统id true string
  authType 指定默认认证类型（打开认证页面所展示的第一个认证类型）
PSN_BANK4_AUTHCODE - 个人银行卡四要素认证
PSN_TELECOM_AUTHCODE - 个人运营商三要素认证
PSN_FACEAUTH_BYURL - 个人刷脸认证
以下方式如需使用，请联系e签宝交付顾问开通：
PSN_AUDIO_VIDEO_ESIGN - 智能视频认证		 false string
  availableAuthTypes 指定页面显示认证方式
PSN_BANK4_AUTHCODE - 个人银行卡四要素认证
PSN_TELECOM_AUTHCODE - 个人运营商三要素认证
PSN_FACEAUTH_BYURL - 个人刷脸认证
以下方式如需使用，请联系e签宝交付顾问开通：
PSN_AUDIO_VIDEO_ESIGN - 智能视频认证		 false array string
  authAdvancedEnabled 指定通过银行卡认证或运营商认证方式时，是否使用详情版，如指定则核验失败可返回具体不匹配信息，传空默认为普通版
PSN_BANK4_AUTHCODE - 个人银行卡四要素认证
PSN_TELECOM_AUTHCODE - 个人运营商三要素认证
【注】详情版：需要单独购买，具体购买方式请咨询e签宝工作人员；
普通版：信息比对核验失败，不会返回具体的不匹配信息		 false array string
  receiveUrlMobileNo 接收实名认证链接短信通知的手机号。传入手机号会发送邀请实名认证短信通知到该用户，并收取一次短信费用，不传入则不发送，不产生短信费用 false string
  indivInfo 个人实名认证的基本信息 false IndivInfo IndivInfo
    bankCardNo 个人银行卡号（仅支持银联卡） false string
    certNo 个人证件号 false string
    certType 个人证件类型
INDIVIDUAL_CH_IDCARD - 中国大陆身份证
INDIVIDUAL_CH_TWCARD - 台湾来往大陆通行证（台胞证）
INDIVIDUAL_CH_HONGKONG_MACAO - 港澳来往大陆通行证（回乡证）
INDIVIDUAL_PASSPORT - 护照
INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW - 港澳台居民居住证（18位810开头）
INDIVIDUAL_CH_GREEN_CARD - 外国人永久居留身份证（18位9开头）		 false string
    mobileNo 个人手机号 false string
    name 个人姓名 false string
  configParams 认证配置信息 false ConfigParams ConfigParams
    indivUneditableInfo 个人认证页面上不可修改的基本信息。传空表示可以修改
name - 姓名
certNo - 证件号
mobileNo - 手机号
bankCardNo - 银行卡号		 false array string
    audioVideoTemplateId 智能视频认证模板ID（可以指定录制视频页面的朗读文案）
【注】：仅在智能视频认证开通后使用，请联系e签宝交付顾问配置后提供		 false string
    audioVideoActiveField 智能视频认证文案中的动态朗读内容，动态内容 Key:Value值（支持自定义key和Value），格式如下：
audioVideoActiveField": {"appName": "开发者平台名","userName": "认证人姓名","bizScene":"签署的文件名"}
【注】：与 audioVideoTemplateId（智能视频认证模板ID）配套使用，请联系e签宝交付顾问进行配置		 false object
  contextInfo 业务方交互上下文信息，有统计需求或者分账需求必填部分参数 false ContextInfo ContextInfo
    contextId 自定义业务标识
在异步通知时发送回发起方，直接对接客户建议上传相关订单Id或会员Id，渠道分销商建议上传客户唯一Id		 false string
    notifyUrl 发起方接收实名认证状态变更通知的地址，异步通知参考 https://open.esign.cn/doc/opendoc/identity_service/awa4m6 false string
    origin 认证发起来源，默认值为 BROWSER
BROWSER - 浏览器
APP - 移动端APP（传APP时，redirectUrl字段必传）		 false string
    redirectUrl 认证成功后页面跳转地址，查看如何跳转回APP https://qianxiaoxia.yuque.com/docs/share/313ef643-b3c6-4f4c-8b90-97f27d58542f? false string
    showResultPage 认证完成是否显示结果页，默认值为 true
true - 显示结果，false - 不显示结果		 false boolean
    maxFrequencyLimit 规定当前流程可使用的认证次数最大上限（包含流程中所有可用的认证方式，比如刷脸、手机号认证、银行卡认证），超过次数则自动终止核身流程，流程失败。默认：不限次数。
【注】：需要联系e签宝交付顾问开启配置后才可使用
可搭配failRedirectUrl一起使用，流程终止失败后自动跳转指定的失败地址
认证次数不包含支付宝刷脸方式，支付宝刷脸次数检测不到
信息比对环节信息不做变更，重复点击报错核验不通过都算一次认证次数		 false string
    failRedirectUrl 认证失败后页面跳转地址，查看如何跳转回APP https://qianxiaoxia.yuque.com/docs/share/313ef643-b3c6-4f4c-8b90-97f27d58542f?【注】：需要联系e签宝交付顾问开启配置后才可使用
如果流程所有认证方式可用次数消耗完，都没有认证成功，则跳转到该认证失败地址		 false string
  certificationPurpose 本次实名用途，默认：INDIVIDUAL（个人认证）
INDIVIDUAL - 个人认证
ORGANIZATION - 企业认证
注：
后续企业认证由法定代表人本人作为经办人认证时可传入ORGANIZATION，用于展示企业数字证书服务协议
后续通过【4要素】企业核身认证 接口传入当前认证流程id，并通过企业四要素核验可直接完成企业实名，无需后续步骤。
需联系e签宝技术人员确认相关配置是否开启后，才可使用		 false string
  orgName 企业名称（本次实名用途为企业认证时需传入）
注：
certificationPurpose传ORGANIZATION时必须传入
需保证当前企业名称和后续【4要素】企业核身认证 接口传入的企业账号中的企业名称一致		 false string
  orgCertNo 企业证件号（本次实名用途为企业认证时需传入）
注：
certificationPurpose传ORGANIZATION时必须传入
需保证当前企业证件号和后续【4要素】企业核身认证 接口传入的企业账号中的企业证件号一致		 false string

响应状态:

状态码 说明 schema
200 OK RIdentityAuthUrlVO

响应参数:

参数名称 参数说明 类型 schema
code integer(int32) integer(int32)
message string
data IdentityAuthUrlVO IdentityAuthUrlVO
  flowId 认证流程ID string
  shortLink 个人实名认证短链接（链接有效期30天）
沙箱环境域名：https://smlt.esign.cn
正式环境域名：https://t.esign.cn		 string
  url 个人实名认证长链接（链接有效期30天）
沙箱环境域名：https://smlfront.esign.cn
正式环境域名：https://idverify.esign.cn
（微信小程序端支持自定义域名） https://open.esign.cn/doc/opendoc/identity_service/no0db8		 string

响应示例:

{
    "code": 200,
    "message": "",
    "data": {
        "flowId": "",
        "shortLink": "",
        "url": ""
    }
}